<!-- HTML header for doxygen 1.8.5-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.17"/>
<title>GenAVB/TSN: Control API usage</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script src="http://www.freescale.com/files/abstract/misc/COLLATERALTEMPLATE_infocenter.js" type="text/javascript" xml:space="preserve"><!-- --></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
  $(document).ready(function() { init_search(); });
/* @license-end */
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="html_custom.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="nxp_logo.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">GenAVB/TSN
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('control_usage.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">Control API usage </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="autotoc_md32"></a>
Introduction</h1>
<p>The control API has been designed as a generic interface to enable the configuration and control of various features of the GenAVB stack by an external application.</p>
<p>It is a bi-directional message-passing interface, allowing the user-space application and the GenAVB stack to exchange (send, receive) control messages through different control channels. Six channel types are currently defined (see <a class="el" href="group__control.html#gabe9c9a1e2ef8ec04e182c12131397b6e">genavb_control_id_t</a>):</p><ul>
<li><a class="el" href="group__control.html#ggabe9c9a1e2ef8ec04e182c12131397b6ead4e4880c606c6f67e911197fc47d942e">GENAVB_CTRL_AVDECC_MEDIA_STACK</a> : this channel can be used by a talker or listener application to be notified about stream connections/disconnections done through AVDECC (either by an external controller, or through the fast-connect mechanism).</li>
<li><a class="el" href="group__control.html#ggabe9c9a1e2ef8ec04e182c12131397b6ea4156f5f3e41aa62ac2875b9ab0c078af">GENAVB_CTRL_AVDECC_CONTROLLER</a> : to be used by an AVDECC controller application.</li>
<li><a class="el" href="group__control.html#ggabe9c9a1e2ef8ec04e182c12131397b6ea6ddd1fb5ebd64cf9896c46f108490b52">GENAVB_CTRL_AVDECC_CONTROLLED</a> : to be used by an application running on a talker or listener, for AECP communication (such as volume control, media track selection, play/stop control...).</li>
<li><a class="el" href="group__control.html#ggabe9c9a1e2ef8ec04e182c12131397b6ea7b2b32bf2f64f4a32b3df6d4a73f1e79">GENAVB_CTRL_MSRP</a> : this channel can be used by a talker or listener application to establish stream reservations and be notified about the status of existing reservations on the network. If AVDECC is not being used, this API becomes mandatory to be able to transmit and receive AVTP streams in an AVB network.</li>
<li><a class="el" href="group__control.html#ggabe9c9a1e2ef8ec04e182c12131397b6ea46e956c671c692062083b949c9778686">GENAVB_CTRL_MVRP</a> : this channel can be used by a talker or listener application to establish VLAN registrations.</li>
<li><a class="el" href="group__control.html#ggabe9c9a1e2ef8ec04e182c12131397b6eaa37877f1b1a49912df22141e0b59f690">GENAVB_CTRL_CLOCK_DOMAIN</a> : this channel can be used by a talker or listener application to set the clock source of a clock domain and receive clock domain status indications.</li>
<li><a class="el" href="group__control.html#ggabe9c9a1e2ef8ec04e182c12131397b6ead6d3c8cf2faabd91279d0b4c3ad62100">GENAVB_CTRL_GPTP</a> : this channel can be used by a talker or listener application to retrieve grand master information from GPTP stack component.</li>
</ul>
<p>Messages are represented by raw memory buffers, with an additional <a class="el" href="group__control.html#ga55b3a83feba03f6cf5bcbc0d7e1438d1">message type</a> parameter to define their type, and a msg_len parameter to specify their length. The following message types are currently available:</p><ul>
<li><a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a39cbe0a54bff1c415102b053715ba479">GENAVB_MSG_MEDIA_STACK_CONNECT</a> and <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a095a48be37e1acdd0409c089cdcf01e8">GENAVB_MSG_MEDIA_STACK_DISCONNECT</a></li>
<li><a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a77d2c87b7915425b355b8518e626890d">GENAVB_MSG_AECP</a></li>
<li><a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1ae542e373579d82aba569749b9d68934a">GENAVB_MSG_ACMP_COMMAND</a> and <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1ac5d935a60c7ab9d8299c2a6a7f82a2db">GENAVB_MSG_ACMP_RESPONSE</a></li>
<li><a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1ae1019acdd71cf9b2a10c9dc7979f1cda">GENAVB_MSG_ADP</a></li>
<li><a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a23aa5dee0314361ccb6d7dcb3eee1d86">GENAVB_MSG_LISTENER_REGISTER</a>, <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1ace15da8a84e04f96a4dcc44a4e9fb880">GENAVB_MSG_LISTENER_DEREGISTER</a>, <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a93687ecf32d4fe74439f15784f7ec4fc">GENAVB_MSG_LISTENER_RESPONSE</a>, <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1abd405d5f8b6af2b105c3b2177d3a2182">GENAVB_MSG_LISTENER_STATUS</a>, <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a1c02418971121d35ce8b5b4a5dda403b">GENAVB_MSG_TALKER_REGISTER</a>, <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a6c7b24e948881a34df187f616bec7dac">GENAVB_MSG_TALKER_DEREGISTER</a>, <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1ae58c0785f0e06cbc9b7b1eb73c2fbafd">GENAVB_MSG_TALKER_RESPONSE</a> and <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1ace12154e27c0f4e27e290415298b281e">GENAVB_MSG_TALKER_STATUS</a>,</li>
<li><a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a927fe2112762f202ba587aaf2558c656">GENAVB_MSG_VLAN_REGISTER</a>, <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a040e44822a0e74124a3eb76864359a33">GENAVB_MSG_VLAN_DEREGISTER</a> and <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a6b63b617efab0e13d01d9a5dabdcb2b3">GENAVB_MSG_VLAN_RESPONSE</a></li>
<li><a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a819eb1c2d192bac22f97d4c5adf8197a">GENAVB_MSG_ERROR_RESPONSE</a></li>
<li><a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a11c3322f88eb26d3b4f5b0b33fded5f1">GENAVB_MSG_CLOCK_DOMAIN_SET_SOURCE</a>, <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a61882e16e8b71e4a39abb7e8eba3c1b8">GENAVB_MSG_CLOCK_DOMAIN_RESPONSE</a>, <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a03a9c5dcbd425fd0673b1d3ec89b01a6">GENAVB_MSG_CLOCK_DOMAIN_GET_STATUS</a> and <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a29ddd2520f2a5c696a7513080cffaed2">GENAVB_MSG_CLOCK_DOMAIN_STATUS</a></li>
<li><a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a54a62cd7b9ebe67c8cc302d13bc93370">GENAVB_MSG_GM_GET_STATUS</a>, <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1ac0b79572e61ce31e1f78ee6421f7b2cc">GENAVB_MSG_GM_STATUS</a></li>
</ul>
<p>Each message type has a corresponding message C structure (defined in detail in the GenAVB public headers) and is usually valid on one specific control channel (with some exceptions). Messages are further divided into commands, responses and indications. Commands/responses are used in pairs (with one response always received after a command is sent) while indications can be sent/received at any time. The following table describes the mapping of message types to control channels and their properties.</p>
<h3><a class="anchor" id="autotoc_md33"></a>
Message types properties</h3>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Message type </th><th class="markdownTableHeadNone">Message structure </th><th class="markdownTableHeadNone">Control channel(s) </th><th class="markdownTableHeadNone">Direction </th><th class="markdownTableHeadNone">Type  </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">Generic message type (1) </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#uniongenavb__media__stack__msg">genavb_media_stack_msg</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_AVDECC_MEDIA_STACK </td><td class="markdownTableBodyNone">- </td><td class="markdownTableBodyNone">-  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">MEDIA_STACK_CONNECT </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__media__stack__connect">genavb_msg_media_stack_connect</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_AVDECC_MEDIA_STACK </td><td class="markdownTableBodyNone">FROM stack </td><td class="markdownTableBodyNone">Indication  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">MEDIA_STACK_DISCONNECT </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__media__stack__disconnect">genavb_msg_media_stack_disconnect</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_AVDECC_MEDIA_STACK </td><td class="markdownTableBodyNone">FROM stack </td><td class="markdownTableBodyNone">Indication  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">Generic message type (1) </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#uniongenavb__controller__msg">genavb_controller_msg</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_AVDECC_CONTROLLER </td><td class="markdownTableBodyNone">- </td><td class="markdownTableBodyNone">-  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">Generic message type (1) </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#uniongenavb__controlled__msg">genavb_controlled_msg</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_AVDECC_CONTROLLED </td><td class="markdownTableBodyNone">- </td><td class="markdownTableBodyNone">-  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">AECP (2) </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__aecp__msg">genavb_aecp_msg</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_AVDECC_CONTROLLER, GENAVB_CTRL_AVDECC_CONTROLLED </td><td class="markdownTableBodyNone">TO/FROM stack </td><td class="markdownTableBodyNone">Any  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">ACMP_COMMAND (2) </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__acmp__command">genavb_acmp_command</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_AVDECC_CONTROLLER </td><td class="markdownTableBodyNone">FROM stack </td><td class="markdownTableBodyNone">Command  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">ACMP_RESPONSE (2) </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__acmp__response">genavb_acmp_response</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_AVDECC_CONTROLLER </td><td class="markdownTableBodyNone">TO stack </td><td class="markdownTableBodyNone">Response  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">ADP (2) </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__adp__msg">genavb_adp_msg</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_AVDECC_CONTROLLER </td><td class="markdownTableBodyNone">TO/FROM stack </td><td class="markdownTableBodyNone">Any  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">Generic message type (1) </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#uniongenavb__msg__msrp">genavb_msg_msrp</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_MSRP </td><td class="markdownTableBodyNone">- </td><td class="markdownTableBodyNone">-  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">LISTENER_REGISTER </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__listener__register">genavb_msg_listener_register</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_MSRP </td><td class="markdownTableBodyNone">TO stack </td><td class="markdownTableBodyNone">Command  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">LISTENER_DEREGISTER </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__listener__deregister">genavb_msg_listener_deregister</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_MSRP </td><td class="markdownTableBodyNone">TO stack </td><td class="markdownTableBodyNone">Command  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">LISTENER_RESPONSE </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__listener__response">genavb_msg_listener_response</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_MSRP </td><td class="markdownTableBodyNone">FROM stack </td><td class="markdownTableBodyNone">Response  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">LISTENER_STATUS </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__listener__status">genavb_msg_listener_status</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_MSRP </td><td class="markdownTableBodyNone">FROM stack </td><td class="markdownTableBodyNone">Indication  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">TALKER_REGISTER </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__talker__register">genavb_msg_talker_register</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_MSRP </td><td class="markdownTableBodyNone">TO stack </td><td class="markdownTableBodyNone">Command  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">TALKER_DEREGISTER </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__talker__deregister">genavb_msg_talker_deregister</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_MSRP </td><td class="markdownTableBodyNone">TO stack </td><td class="markdownTableBodyNone">Command  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">TALKER_RESPONSE </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__talker__response">genavb_msg_talker_response</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_MSRP </td><td class="markdownTableBodyNone">FROM stack </td><td class="markdownTableBodyNone">Response  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">TALKER_STATUS </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__talker__status">genavb_msg_talker_status</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_MSRP </td><td class="markdownTableBodyNone">FROM stack </td><td class="markdownTableBodyNone">Indication  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">Generic message type (1) </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#uniongenavb__msg__mvrp">genavb_msg_mvrp</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_MVRP </td><td class="markdownTableBodyNone">- </td><td class="markdownTableBodyNone">-  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">VLAN_REGISTER </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__vlan__register">genavb_msg_vlan_register</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_MVRP </td><td class="markdownTableBodyNone">TO stack </td><td class="markdownTableBodyNone">Command  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">VLAN_DEREGISTER </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__vlan__deregister">genavb_msg_vlan_deregister</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_MVRP </td><td class="markdownTableBodyNone">TO stack </td><td class="markdownTableBodyNone">Command  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">VLAN_RESPONSE </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__vlan__response">genavb_msg_vlan_response</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_MVRP </td><td class="markdownTableBodyNone">FROM stack </td><td class="markdownTableBodyNone">Response  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">Generic message type (1) </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#uniongenavb__msg__clock__domain">genavb_msg_clock_domain</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_CLOCK_DOMAIN </td><td class="markdownTableBodyNone">- </td><td class="markdownTableBodyNone">-  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">CLOCK_DOMAIN_SET_SOURCE </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__clock__domain__set__source">genavb_msg_clock_domain_set_source</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_CLOCK_DOMAIN </td><td class="markdownTableBodyNone">TO stack </td><td class="markdownTableBodyNone">Command  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">CLOCK_DOMAIN_RESPONSE </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__clock__domain__response">genavb_msg_clock_domain_response</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_CLOCK_DOMAIN </td><td class="markdownTableBodyNone">FROM stack </td><td class="markdownTableBodyNone">Response  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">CLOCK_DOMAIN_GET_STATUS </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__clock__domain__get__status">genavb_msg_clock_domain_get_status</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_CLOCK_DOMAIN </td><td class="markdownTableBodyNone">TO stack </td><td class="markdownTableBodyNone">Command  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">CLOCK_DOMAIN_STATUS </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__clock__domain__status">genavb_msg_clock_domain_status</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_CLOCK_DOMAIN </td><td class="markdownTableBodyNone">FROM stack </td><td class="markdownTableBodyNone">Response/Indication  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">GM_GET_STATUS </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__gm__get__status">genavb_msg_gm_get_status</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_GPTP </td><td class="markdownTableBodyNone">TO stack </td><td class="markdownTableBodyNone">Command  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">GM_STATUS </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__gm__status">genavb_msg_gm_status</a> </td><td class="markdownTableBodyNone">GENAVB_CTRL_GPTP </td><td class="markdownTableBodyNone">FROM stack </td><td class="markdownTableBodyNone">Response/Indication  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">ERROR_RESPONSE (3) </td><td class="markdownTableBodyNone"><a class="el" href="group__control.html#structgenavb__msg__error__response">genavb_msg_error_response</a> </td><td class="markdownTableBodyNone">all </td><td class="markdownTableBodyNone">FROM stack </td><td class="markdownTableBodyNone">Response  </td></tr>
</table>
<p>(1) These message structures provide an easy way for the application to allocate a buffer large enough to receive any of the supported message types for a given control channel.</p>
<p>(2) These messages encapsulate PDU's as defined in IEEE 1722.1-2011 and need further decoding to identify their specific type.</p>
<p>(3) This is a generic error response, valid in any control channel type.</p>
<p>A control channel is opened using the <a class="el" href="group__control.html#ga5578fc52cccd9d59af19d6301c997b30">genavb_control_open</a> API. The API returns a handle that must be used in all other control API's.</p>
<p>Message reception by the application is done with the <a class="el" href="group__control.html#gaf98c2c44f87c3315ab02060426128f5b">genavb_control_receive</a> function. This call is non-blocking, so it will report an error if no message is available on the given control channel.</p>
<p>A callback can be registered using <a class="el" href="group__control.html#ga3e1d22e6b4342f790bf25356bd2ce3ca" title="Sets notification callback for a given control channel.">genavb_control_set_callback</a> which is called when received data is available. The callback must not block and should notify another task which performs the actual data reception. After the callback has been called it must be re-armed by calling <a class="el" href="group__control.html#ga5bae84d73770286c9225bd9581163133" title="Enables notification callback for a given control channel.">genavb_control_enable_callback</a>. This should be done after the application has read all data available/written all data available (and never from the callback itself).</p>
<p>Sending a message can be performed in two different ways by the application:</p><ul>
<li>using <a class="el" href="group__control.html#ga5fd11898e51c3fc774946f7c87e830ec">genavb_control_send</a> : the application will post the message, and the call will return as soon as the message is sent without waiting for any reply from the stack. If a response is expected, <a class="el" href="group__control.html#gaf98c2c44f87c3315ab02060426128f5b">genavb_control_receive</a> should be called afterwards to fetch it. There is no guarantee however that the first available message will be the response to the command just sent: other messages may arrive in-between, so the application should make sure those are handled as well.</li>
<li>using <a class="el" href="group__control.html#ga7aeadc33999c312331793c2eddff0a8c">genavb_control_send_sync</a> : this call will post the message and wait for a response from the stack. This can be simpler for the application when a response is needed and it doesn't need to do anything else in the mean time, since the stack will take care of providing the response message matching the command. Other messages can still be fetched normally afterwards using <a class="el" href="group__control.html#gaf98c2c44f87c3315ab02060426128f5b">genavb_control_receive</a>.</li>
</ul>
<p>There are no restrictions on which channel types and message types can be used with each mode, so it is entirely up to the application to use whichever mode makes more sense for its use cases.</p>
<p>To close a control channel use <a class="el" href="group__control.html#gad0841cb96924749eeaab72a3dc3af8bd">genavb_control_close</a>.</p>
<h1><a class="anchor" id="autotoc_md34"></a>
Restrictions</h1>
<p>Each control channel may be opened by a single application in the system. Also, if multiple threads send/receive from the same control channel, locking should be provided by the application. Typically, responses to commands sent from thread X, can be received by thread Y.</p>
<hr  />
<h1><a class="anchor" id="autotoc_md36"></a>
Clock Domain control API</h1>
<p>This API uses a <a class="el" href="group__control.html#ggabe9c9a1e2ef8ec04e182c12131397b6eaa37877f1b1a49912df22141e0b59f690">GENAVB_CTRL_CLOCK_DOMAIN</a> control channel and interacts with the AVTP stack component. It allows to configure the clock domain (<a class="el" href="group__stream.html#ga549fd464aad79090311d03274e0f5ffb">genavb_clock_domain_t</a>) in a way close to IEEE 1722.1-2011 description.</p>
<h3><a class="anchor" id="autotoc_md37"></a>
Clock domain</h3>
<p>The clock domain can refer to an audio or a video clock domain. Any member of a clock domain is synchronous to the domain clock source and is able to exchange media data with the other members.</p>
<p>The clock domain ID (<a class="el" href="group__stream.html#ga549fd464aad79090311d03274e0f5ffb">genavb_clock_domain_t</a>) makes the link between the streams and the clock devices registered to the media clock layer of genAVB stack. The clock device drivers are platform specific and documented in the platform specific section.</p>
<p>Note: the domain ID is used by the media clock platform specific layer to find clock device drivers which have been registered.</p>
<h3><a class="anchor" id="autotoc_md38"></a>
Setting the clock domain source</h3>
<p>The application can set the clock source of the domain through the <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a11c3322f88eb26d3b4f5b0b33fded5f1">GENAVB_MSG_CLOCK_DOMAIN_SET_SOURCE</a> command with <a class="el" href="group__control.html#structgenavb__msg__clock__domain__set__source">genavb_msg_clock_domain_set_source</a> structure. This command receives the response <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a61882e16e8b71e4a39abb7e8eba3c1b8">GENAVB_MSG_CLOCK_DOMAIN_RESPONSE</a> with <a class="el" href="group__control.html#structgenavb__msg__clock__domain__response">genavb_msg_clock_domain_response</a>. The clock domain is considered configured and in a valid state only if status field of <a class="el" href="group__control.html#structgenavb__msg__clock__domain__response">genavb_msg_clock_domain_response</a> is equal to <a class="el" href="group__generic.html#gga031a0b2111b623fef60d707141a995d5a652003ceb0485f27d4a45e7c29dffe7f">GENAVB_SUCCESS</a>.</p>
<p><em>Important</em>: The clock domain needs to be configured before creating streams. If <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a11c3322f88eb26d3b4f5b0b33fded5f1">GENAVB_MSG_CLOCK_DOMAIN_SET_SOURCE</a> command is used while active streams are configured, only a valid status from <a class="el" href="group__control.html#structgenavb__msg__clock__domain__response">genavb_msg_clock_domain_response</a> guarantees that all configured streams are in a valid state. If the return status is not successful, the clock domain is considered to be in an invalid state and streaming is disabled. It is the application responsability to send an other <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a11c3322f88eb26d3b4f5b0b33fded5f1">GENAVB_MSG_CLOCK_DOMAIN_SET_SOURCE</a> until a succesful response is received.</p>
<h3><a class="anchor" id="autotoc_md39"></a>
Source types</h3>
<p>Two top-level source types are available <a class="el" href="group__control.html#ga43c88bbe8d7e5a7604bd1dafde4bd33e">genavb_clock_source_type_t</a></p>
<p><a class="el" href="group__control.html#gga43c88bbe8d7e5a7604bd1dafde4bd33eab81529492ec8c4dddc1249a02dc049e8">GENAVB_CLOCK_SOURCE_TYPE_INTERNAL</a> is used for an internal clock source. It is used for master endpoints which need to provide their own timing information to the domain. 2 types of internal clocks are supported as defined in <a class="el" href="group__control.html#ga70b98e498527a1671616b100901ff262">genavb_clock_source_local_id_t</a> :</p><ul>
<li><a class="el" href="group__control.html#gga70b98e498527a1671616b100901ff262ad1b580ced09a7a4cd4bb02ffebcaaef4">GENAVB_CLOCK_SOURCE_AUDIO_CLK</a> The timing source is the physical audio clock of the audio codec associated to the domain. This source type requires a generation clock device associated to the audio codec clock with HW support. The association between a domain ID and the audio codec is described in the platform specific section. It is used when the media frames are played/captured to/from a HW audio device.</li>
<li><a class="el" href="group__control.html#gga70b98e498527a1671616b100901ff262a11e9dc10dd142ab65737f001ea387d76">GENAVB_CLOCK_SOURCE_PTP_CLK</a> The timing source is a perfect gPTP based clock generated in software. It is generally used when the media frames are played/captured to/from a file. This clock source has a clock device which is not associated to a given domain ID.</li>
</ul>
<p><a class="el" href="group__control.html#gga43c88bbe8d7e5a7604bd1dafde4bd33ea401446d9b8b8e9e30008f2cd8187e918">GENAVB_CLOCK_SOURCE_TYPE_INPUT_STREAM</a> is used when the clock source is a remote stream. The remote stream can be any listener stream of any format. It is used by slave endpoints which need to synchronise their clock domain to a remote master. This source type requires a recovery clock device associated to the audio codec. The association between a domain ID and the audio codec is described in the platform specific section.</p>
<h3><a class="anchor" id="autotoc_md40"></a>
Clock source types summary</h3>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Clock source type </th><th class="markdownTableHeadNone">Clock source type local ID </th><th class="markdownTableHeadNone">Requirement </th><th class="markdownTableHeadNone">Typical use case  </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">GENAVB_CLOCK_SOURCE_TYPE_INTERNAL </td><td class="markdownTableBodyNone">GENAVB_CLOCK_SOURCE_AUDIO_CLK </td><td class="markdownTableBodyNone">Generation clock device </td><td class="markdownTableBodyNone">Master, audio codec  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft">GENAVB_CLOCK_SOURCE_TYPE_INTERNAL </td><td class="markdownTableBodyNone">GENAVB_CLOCK_SOURCE_PTP_CLK </td><td class="markdownTableBodyNone">None (software) </td><td class="markdownTableBodyNone">Master, slave, file server  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft">GENAVB_CLOCK_SOURCE_TYPE_STREAM </td><td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone">Recovery clock device </td><td class="markdownTableBodyNone">Slave, audio codec  </td></tr>
</table>
<h3><a class="anchor" id="autotoc_md41"></a>
Indications</h3>
<p>It is possible to get status on the clock domain by listening <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a29ddd2520f2a5c696a7513080cffaed2">GENAVB_MSG_CLOCK_DOMAIN_STATUS</a> indications (using <a class="el" href="group__control.html#gaf98c2c44f87c3315ab02060426128f5b">genavb_control_receive</a>).</p>
<p>Note: These messages are in beta state.</p>
<hr  />
<h1><a class="anchor" id="autotoc_md43"></a>
MSRP control API</h1>
<p>This API uses a <a class="el" href="group__control.html#ggabe9c9a1e2ef8ec04e182c12131397b6ea7b2b32bf2f64f4a32b3df6d4a73f1e79">GENAVB_CTRL_MSRP</a> control channel and interacts with the SRP stack component. It allows a Talker/Listener application to make stream reservations on an AVB network (through SRP as specificed in 802.1Qat-2010). The API also allows the application to be notified of existing reservations (made by other endpoints) and their status. If the AVDECC stack component is enabled, stream reservations are done automatically (for streams connected through AVDECC) and it's not required for the application to use this API.</p>
<h3><a class="anchor" id="autotoc_md44"></a>
Talker streams</h3>
<p>A Talker can register streams on the network through the <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a1c02418971121d35ce8b5b4a5dda403b">GENAVB_MSG_TALKER_REGISTER</a> command. To deregister a stream the <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a6c7b24e948881a34df187f616bec7dac">GENAVB_MSG_TALKER_DEREGISTER</a> command is used. Both commands receive the same response <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1ae58c0785f0e06cbc9b7b1eb73c2fbafd">GENAVB_MSG_TALKER_RESPONSE</a>.</p>
<p>To learn about the existing Listeners for registered Talker streams, the application can listen to <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1ace12154e27c0f4e27e290415298b281e">GENAVB_MSG_TALKER_STATUS</a> indications (using <a class="el" href="group__control.html#gaf98c2c44f87c3315ab02060426128f5b">genavb_control_receive</a>).</p>
<h3><a class="anchor" id="autotoc_md45"></a>
Listener streams</h3>
<p>A Listener can register the streams it wishes to receive through the <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a23aa5dee0314361ccb6d7dcb3eee1d86">GENAVB_MSG_LISTENER_REGISTER</a> command. To deregister a stream the <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1ace15da8a84e04f96a4dcc44a4e9fb880">GENAVB_MSG_LISTENER_DEREGISTER</a> command is used. Both commands receive the same response <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a93687ecf32d4fe74439f15784f7ec4fc">GENAVB_MSG_LISTENER_RESPONSE</a>.</p>
<p>To learn about the Talker status for registered Listener streams, the application can listen to <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1abd405d5f8b6af2b105c3b2177d3a2182">GENAVB_MSG_LISTENER_STATUS</a> indications (using <a class="el" href="group__control.html#gaf98c2c44f87c3315ab02060426128f5b">genavb_control_receive</a>).</p>
<hr  />
<h1><a class="anchor" id="autotoc_md47"></a>
GPTP control API</h1>
<p>This API uses a <a class="el" href="group__control.html#ggabe9c9a1e2ef8ec04e182c12131397b6ead6d3c8cf2faabd91279d0b4c3ad62100">GENAVB_CTRL_GPTP</a> control channel and interacts with the GPTP stack component. It allows a Talker/Listener application to retrieve the status of the GPTP Grand Master. The API also allows the application to be notified of Grand Master status changes.</p>
<hr  />
<h1><a class="anchor" id="autotoc_md49"></a>
AVDECC control API</h1>
<p>The API has been designed to expose most of the AVDECC functionality to a user-space application, while hiding out protocol interaction details.</p>
<p>It can be used by an AVDECC controller to:</p><ul>
<li>connect and disconnect streams,</li>
<li>get information about AVDECC entities,</li>
<li>send AECP commands and receive responses.</li>
</ul>
<p>It can be used by an application on an AVDECC talker or listener entity to:</p><ul>
<li>receive stream connection/disconnection messages,</li>
<li>receive AECP commands and send responses.</li>
</ul>
<div class="image">
<img src="avdecc_control.png" alt=""/>
<div class="caption">
AVDECC control paths</div></div>
   <hr  />
<h2><a class="anchor" id="autotoc_md51"></a>
Exchanges on an @ref GENAVB_CTRL_AVDECC_MEDIA_STACK channel</h2>
<p>This channel can be used by a media stack application to be notified about stream connections/disconnections.</p>
<p>When a stream is connected, the stack will send a <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a39cbe0a54bff1c415102b053715ba479">GENAVB_MSG_MEDIA_STACK_CONNECT</a> message, whose content maps to the <a class="el" href="group__stream.html#structgenavb__stream__params">genavb_stream_params</a> structure. It normally contains all the necessary parameters to initialize the media stack. It is also the same structure that is required by the <a class="el" href="group__stream.html#ga1edca94485ef63e234a5012187255588">genavb_stream_create</a> function to create an AVTP stream, so it may be passed as is by the media stack application.</p>
<p>When a stream is disconnected, the stack will send a <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a095a48be37e1acdd0409c089cdcf01e8">GENAVB_MSG_MEDIA_STACK_DISCONNECT</a> message, mapping the genavb_stream_disconnect structure.</p>
<blockquote class="doxtable">
<p>The <a class="el" href="group__control.html#ggabe9c9a1e2ef8ec04e182c12131397b6ead4e4880c606c6f67e911197fc47d942e">GENAVB_CTRL_AVDECC_MEDIA_STACK</a> channel should not be confused with the stream creation API: it is only used to receive stream connections/disconnections </p>
</blockquote>
<p>messages received through the AVDECC protocol, and it is then the responsibility of the application to actually request creation/destruction of the stream in the AVTP component of the stack, using the <a class="el" href="group__stream.html#ga1edca94485ef63e234a5012187255588">genavb_stream_create</a> and <a class="el" href="group__stream.html#ga8ad1f9febe073b91fadc3b3aca802398">genavb_stream_destroy</a> functions.</p>
<hr  />
<h2><a class="anchor" id="autotoc_md53"></a>
ACMP exchanges on an @ref GENAVB_CTRL_AVDECC_CONTROLLER channel</h2>
<p>ACMP messages can be used by a controller to request the connection or disconnection of AVTP streams on the AVB network, and to get information about the existing streams.</p>
<p>ACMP commands may be sent by a controller application through the <a class="el" href="group__control.html#ggabe9c9a1e2ef8ec04e182c12131397b6ea4156f5f3e41aa62ac2875b9ab0c078af">GENAVB_CTRL_AVDECC_CONTROLLER</a> channel, using the GENAVB_MSG_ACMP message type and the <a class="el" href="group__control.html#structgenavb__acmp__command">genavb_acmp_command</a> structure. Only commands that a controller entity may send (according the specification) are allowed:</p><ul>
<li><a class="el" href="group__control.html#gga23209314df1f8a256ff131c24c0e713fadf908dc603c9b60a3eb8777f83980122">ACMP_CONNECT_RX_COMMAND</a> ,</li>
<li><a class="el" href="group__control.html#gga23209314df1f8a256ff131c24c0e713faa4bb1c9f389289109ab89f4568878dba">ACMP_DISCONNECT_RX_COMMAND</a> ,</li>
<li><a class="el" href="group__control.html#gga23209314df1f8a256ff131c24c0e713fa1c2063333a2e6101c7f890ffbea6a8de">ACMP_GET_TX_STATE_COMMAND</a> ,</li>
<li><a class="el" href="group__control.html#gga23209314df1f8a256ff131c24c0e713fa02df94c4ce569eed313ab11d414cba64">ACMP_GET_RX_STATE_COMMAND</a> ,</li>
<li><a class="el" href="group__control.html#gga23209314df1f8a256ff131c24c0e713fada8d35c8f6c43bcdcd65677de761bc7a">ACMP_GET_TX_CONNECTION_COMMAND</a> .</li>
</ul>
<p>The stack will post the ACMP responses on that same channel, using the GENAVB_MSG_ACMP message type and the <a class="el" href="group__control.html#structgenavb__acmp__response">genavb_acmp_response</a> structure.</p>
<p>The content of the <a class="el" href="group__control.html#structgenavb__acmp__command">genavb_acmp_command</a> and <a class="el" href="group__control.html#structgenavb__acmp__response">genavb_acmp_response</a> structures closely matches the ACMP specification, so the AVDECC standard should be referred to for additional details. To simplify the task of the application however, the GenAVB stack will handle all the network-related tasks, such as retransmission on timeout.</p>
<blockquote class="doxtable">
<p>Since there are no notification mechanisms in the ACMP specification, the stack will never send any ACMP messages to the application without receiving an ACMP command from the application first. </p>
</blockquote>
<hr  />
<h2><a class="anchor" id="autotoc_md55"></a>
ADP exchanges on an @ref GENAVB_CTRL_AVDECC_CONTROLLER channel</h2>
<p>Handling ADP messages will allow a controller application to maintain an up-to-date view of the AVDECC entities discovered on the AVB network by the GenAVB stack.</p>
<p>ADP messages use the <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1ae1019acdd71cf9b2a10c9dc7979f1cda">GENAVB_MSG_ADP</a> message type and the <a class="el" href="group__control.html#structgenavb__adp__msg">genavb_adp_msg</a> structure.</p>
<p>Each time an entity becomes available on or departs the network, the stack will send an ADP message to the application, with the msg_type field of the <a class="el" href="group__control.html#structgenavb__adp__msg">genavb_adp_msg</a> structure set respectively to ADP_ENTITY_AVAILABLE or ADP_ENTITY_DEPARTING. The info field of that structure will contain additional details on the entity. ADP_ENTITY_AVAILABLE messages will also be sent by the stack if the entity was updated in any way, but not for the simple refresh messages sent periodically by the remote entity. The stack however will age the entities according to the (non)-received messages, and it remove entites that are no longer visible from its database. When this happens, the application will also be notified of the departing entity.</p>
<p>The application may also request specific information by sending ADP messages to the stack:</p><ul>
<li>Messages from the application with the msg_type (of the <a class="el" href="group__control.html#structgenavb__adp__msg">genavb_adp_msg</a> structure) set to ADP_ENTITY_DISCOVER will trigger a dump of all currently discovered entities. Each discovered entity will be notified to the application with its own ADP_ENTITY_AVAILABLE message (one single entity per message). This can be useful on startup for the application to sync its state with that of the stack. The total field can be used by the application to determine when its view of the network is complete (i.e. when it has received information about total different entities).</li>
<li>To get information about a specific entity, the application shall set msg_type to ADP_ENTITY_AVAILABLE, info.entity_id to the AVDECC id of the requested entity, with the other fields being unused. The stack will reply with the corresponding entity if it exists.</li>
</ul>
<p>If no entity was found or if an invalid msg_type was used, a reply will be sent by the stack to the application with msg_type set to ADP_ENTITY_NOTFOUND.</p>
<hr  />
<h2><a class="anchor" id="autotoc_md57"></a>
AECP exchanges</h2>
<p>AECP communication may happen through either the <a class="el" href="group__control.html#ggabe9c9a1e2ef8ec04e182c12131397b6ea4156f5f3e41aa62ac2875b9ab0c078af">GENAVB_CTRL_AVDECC_CONTROLLER</a> or <a class="el" href="group__control.html#ggabe9c9a1e2ef8ec04e182c12131397b6ea6ddd1fb5ebd64cf9896c46f108490b52">GENAVB_CTRL_AVDECC_CONTROLLED</a> channels, depending on the type of the entity sending/receiving the messages. A controller can use AECP messages to request specific information about an entity, or request actions to be performed by the entity. A talker or Listener application can use AECP messages to reply to commands from a controller (such as get/set volume, etc), and also notify the stack of changes within the entity (such as a volume change event from outside AVDECC), so that the stack can then forward the message to interested entities (usually controllers registered for unsolicited notifications).</p>
<p>AECP messages use the <a class="el" href="group__control.html#gga55b3a83feba03f6cf5bcbc0d7e1438d1a77d2c87b7915425b355b8518e626890d">GENAVB_MSG_AECP</a> message type and the <a class="el" href="group__control.html#structgenavb__aecp__msg">genavb_aecp_msg</a> structure. Of all the AECP types, only the AEM ones are currently supported by the stack. Because of the breadth of the AECP AEM protocol, the various AECP AEM PDUs are mapped as is into the buf field of the <a class="el" href="group__control.html#structgenavb__aecp__msg">genavb_aecp_msg</a> structure. Additional information such as the AECP msg_type and AECP status is also available in that structure. Additional details about those fields and the format of AECP AEM PDUs may be found in the AVDECC standard. To simplify the task of the application however, the GenAVB stack will handle all the network-related tasks, such as retransmission on timeout and controller locking/availability checks. A controller application can therefore simply send commands (and possibly wait for a response), without having to worry about other details. Similarly, a talker or listener may simply send messages to the stack when it needs to, without worrying about potential network protocol issues.</p>
<h3><a class="anchor" id="autotoc_md58"></a>
AEM model support</h3>
<p>The AEM models to be used by the stack are currently defined and generated at compile-time through the aem-manager host application, whose source code is provided in the apps/linux folder.The GenAVB stack will load AEM model files at run-time (based on command-line parameters for the Linux platform). More than one AEM model may be loaded, will the following constraints:</p><ul>
<li>at most one controller entity may be declared per endpoint,</li>
<li>at most one non-controller entity (talker or listener) may be declared per endpoint.</li>
</ul>
<p>This means in practice, only up to 2 entities may be declared per endpoint. Those limitations might be lifted in future versions of the stack.</p>
<p>Dynamically updating the AEM model at run-time is also not possible currently, but changing the value(s) stored in a CONTROL descriptor is. The stack maintains its own view of the whole AEM model, so that <a class="el" href="group__aem.html#ggae99a25757035d67d1e38e288f857ff41aae582b03e74b1c7cc03b18a577212ae8" title="GET_CONTROL command/response.">AECP_AEM_CMD_GET_CONTROL</a> commands can be replied to without involving the application. However, the application <em>has to</em> notify the stack of changes in the values stored in a CONTROL descriptor, by sending the relevant <a class="el" href="group__aem.html#ggae99a25757035d67d1e38e288f857ff41ad2319757d74d77aad53043e893c96f83" title="SET_CONTROL command/response.">AECP_AEM_CMD_SET_CONTROL</a> unsolicited response in reaction to a change made outside AVDECC. For consistency however the stack will never update the values immediately upon reception of a <a class="el" href="group__aem.html#ggae99a25757035d67d1e38e288f857ff41ad2319757d74d77aad53043e893c96f83" title="SET_CONTROL command/response.">AECP_AEM_CMD_SET_CONTROL</a> command from a controller: this ensures the application can perform additional validation steps on the requested value and report any issue back to the stack.In conclusion, CONTROL descriptor values are updated either by the value received from a controller in the <a class="el" href="group__aem.html#ggae99a25757035d67d1e38e288f857ff41ad2319757d74d77aad53043e893c96f83" title="SET_CONTROL command/response.">AECP_AEM_CMD_SET_CONTROL</a> command (once stack validate it on reception and application respond with <a class="el" href="group__aem.html#gga28c8fb55a44ef0fa9474dadb507180b7a68d0c6724ca69737507f1f7b07afd4c3" title="The AVDECC Entity successfully performed the command and has valid results.">AECP_AEM_SUCCESS</a> in <a class="el" href="group__control.html#ac8402298d013b7bf0b1e09feebd6ea42" title="status field, from aecp_status_t.">genavb_aecp_msg.status</a>) or by a valid value from a <a class="el" href="group__aem.html#ggae99a25757035d67d1e38e288f857ff41ad2319757d74d77aad53043e893c96f83" title="SET_CONTROL command/response.">AECP_AEM_CMD_SET_CONTROL</a> unsolicited response sent by application.</p>
<blockquote class="doxtable">
<p>Only 2 value types are currently fully supported by the stack for CONTROL descriptors: LINEAR_UINT8 and UTF8. </p>
</blockquote>
<h3><a class="anchor" id="autotoc_md59"></a>
AECP exchanges on an @ref GENAVB_CTRL_AVDECC_CONTROLLER channel</h3>
<p>On such a channel:</p><ul>
<li>Only commands shall be sent by the application (<a class="el" href="group__control.html#a724d635b0c0855e5787fff8e9069305f" title="AECP message_type, from aecp_message_type_t.">genavb_aecp_msg.msg_type</a> == <a class="el" href="group__aem.html#gga1a819286f45ec4d69fb995627756d840a7698d47e4fbc8d3e54b8bd2648c5c1a2" title="AECP message type, AEM command.">AECP_AEM_COMMAND</a>),</li>
<li>Only responses will be sent by the stack and received by the application (<a class="el" href="group__control.html#a724d635b0c0855e5787fff8e9069305f" title="AECP message_type, from aecp_message_type_t.">genavb_aecp_msg.msg_type</a> == <a class="el" href="group__aem.html#gga1a819286f45ec4d69fb995627756d840ac45526acdf58341f0ce63e36a7f0c09d" title="AECP message type, AEM response.">AECP_AEM_RESPONSE</a>).</li>
</ul>
<p><a class="el" href="group__aem.html#a63b4b597840f92816e511c30ef4dfb66" title="ID of the controller sending (if the message is a command), or receiving (if the message is a respons...">aecp_pdu.controller_entity_id</a>, <a class="el" href="group__aem.html#a9e38b922a840a8cd7ecad5f75ba09454" title="Sequence ID of the message, determined by the controller that sent the command (if any).">aecp_pdu.sequence_id</a> will be overwritten by the stack before sending the message on the network and can be safely ignored by the application. The stack will check the entity ID (<a class="el" href="group__aem.html#a26c626daa5962edfb212afabd7f48b79" title="ID of the entity targeted by (if the message is a command), or sending (if the message is a response)...">aecp_pdu.entity_id</a>) provided by the application, and:</p><ul>
<li>If it is 0, it will send the command to the first discovered entity (talker or listener),</li>
<li>Otherwise, it will make sure the entity is currently available (based on the database of entities maintained by the ADP component of the stack), and send the command to it. The stack will report an error if no entity could be found.</li>
</ul>
<p>Aside from the entity ID check and network protocol handling, the stack acts mostly as a pass-through in this case, and the commands/responses will be sent from/to the application without any modification.</p>
<h3><a class="anchor" id="autotoc_md60"></a>
AECP exchanges on an @ref GENAVB_CTRL_AVDECC_CONTROLLED channel</h3>
<p>On such a channel:</p><ul>
<li>Only responses shall be sent by the application,</li>
<li>Only commands will be sent by the stack and received by the application.</li>
</ul>
<p>Not all commands are supported by the stack for network reception yet. When possible, commands are also handled directly without disturbing the application. As a result, only a limited set of commands may be received by the application. The table below lists the commands currently supported by the stack for reception from the network for talker or listener entities. </p><table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">Command </th><th class="markdownTableHeadCenter">Handled by the stack </th><th class="markdownTableHeadCenter">Passed to the application  </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">AECP_AEM_CMD_READ_DESCRIPTOR </td><td class="markdownTableBodyCenter">Y </td><td class="markdownTableBodyCenter">N  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">AECP_AEM_CMD_ACQUIRE_ENTITY </td><td class="markdownTableBodyCenter">Partial* </td><td class="markdownTableBodyCenter">N  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">AECP_AEM_CMD_REGISTER_UNSOLICITED_NOTIFICATION </td><td class="markdownTableBodyCenter">Y </td><td class="markdownTableBodyCenter">N  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">AECP_AEM_CMD_DEREGISTER_UNSOLICITED_NOTIFICATION </td><td class="markdownTableBodyCenter">Y </td><td class="markdownTableBodyCenter">N  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">AECP_AEM_CMD_SET_CONTROL </td><td class="markdownTableBodyCenter">Y </td><td class="markdownTableBodyCenter">Y  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">AECP_AEM_CMD_GET_CONTROL </td><td class="markdownTableBodyCenter">Y </td><td class="markdownTableBodyCenter">N  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">AECP_AEM_CMD_START_STREAMING </td><td class="markdownTableBodyCenter">Y </td><td class="markdownTableBodyCenter">Y  </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">AECP_AEM_CMD_STOP_STREAMING </td><td class="markdownTableBodyCenter">Y </td><td class="markdownTableBodyCenter">Y  </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">Others </td><td class="markdownTableBodyCenter">N </td><td class="markdownTableBodyCenter">N  </td></tr>
</table>
<blockquote class="doxtable">
<p>*The ACQUIRE_ENTITY command is implemented, with the following limitations:</p><ul>
<li>No CONTROLLER_AVAILABLE checks are being performed in this case</li>
<li>The acquiring controller will not be sent unsolicited responses as mandated by the AVDECC specification, unless it did register for unsolicited notifications as well.</li>
<li>Only whole entities can be acquired, and not other descriptors. </li>
</ul>
</blockquote>
<h4><a class="anchor" id="autotoc_md61"></a>
Handling of SET_CONTROL command</h4>
<p>When receiving a <a class="el" href="group__aem.html#ggae99a25757035d67d1e38e288f857ff41ad2319757d74d77aad53043e893c96f83" title="SET_CONTROL command/response.">AECP_AEM_CMD_SET_CONTROL</a> command from the network, the stack will (in that order):</p><ul>
<li>Make sure the requested CONTROL descriptor can be found in the AEM model loaded in memory and is not read-only,</li>
<li>Make sure the requested value is valid,</li>
<li>Pass the command to the application,</li>
<li>Send IN_PROGRESS responses to the requesting controller until the application provides a response.In case the application does not respond with a proper msg after sending AECP_CFG_MAX_AEM_IN_PROGRESS messages (A total of 10 seconds period) the stack will send a <a class="el" href="group__aem.html#ggae99a25757035d67d1e38e288f857ff41ad2319757d74d77aad53043e893c96f83" title="SET_CONTROL command/response.">AECP_AEM_CMD_SET_CONTROL</a> failure response.</li>
</ul>
<h4><a class="anchor" id="autotoc_md62"></a>
Handling of START_STREAMING and STOP_STREAMING commands</h4>
<p>When receiving a START_STREAMING or STOP_STREAMING command from the network, the stack will (in that order):</p><ul>
<li>Make sure the requested STREAM descriptor can be found in the AEM model loaded in memory and is not read-only,</li>
<li>Pass the command to the application,</li>
<li>Send IN_PROGRESS responses to the requesting controller until the application provides a response.</li>
</ul>
<h4><a class="anchor" id="autotoc_md63"></a>
Responses from the application</h4>
<p>A talker or listener application may send responses through an <a class="el" href="group__control.html#ggabe9c9a1e2ef8ec04e182c12131397b6ea6ddd1fb5ebd64cf9896c46f108490b52">GENAVB_CTRL_AVDECC_CONTROLLED</a> channel at any time. The entity ID field of the response message coming from the application will be ignored: the stack will determine the entity the response should originate from on its own, under the assumption that only one non-controller entity is declared on the endpoint (only one non-controller entity per endpoint is currently supported). If no non-controller entity has been declared on the endpoint, the message will be ignored. If the response is not related to an AECP command previously received by the application, the U bit (in <a class="el" href="group__aem.html#a2453ca57616674f45f6e32646d58ab74" title="Bit field of U bit (1 for unsolicited responses, 0 in all other cases) and aecp_aem_command_type_t.">aecp_aem_pdu.u_command_type</a>) shall be set to 1 by the application, and the <a class="el" href="group__aem.html#a63b4b597840f92816e511c30ef4dfb66" title="ID of the controller sending (if the message is a command), or receiving (if the message is a respons...">aecp_pdu.controller_entity_id</a>, <a class="el" href="group__aem.html#a9e38b922a840a8cd7ecad5f75ba09454" title="Sequence ID of the message, determined by the controller that sent the command (if any).">aecp_pdu.sequence_id</a> fields will be ignored by the stack. Otherwise (the response is in reply to a received command), the U bit shall be set to 0 and the <a class="el" href="group__aem.html#a63b4b597840f92816e511c30ef4dfb66" title="ID of the controller sending (if the message is a command), or receiving (if the message is a respons...">aecp_pdu.controller_entity_id</a>, <a class="el" href="group__aem.html#a9e38b922a840a8cd7ecad5f75ba09454" title="Sequence ID of the message, determined by the controller that sent the command (if any).">aecp_pdu.sequence_id</a> fields shall match the value from the command message.</p>
<p>After receiving a (response) message from the application and finding the corresponding entity, the stack will (in that order):</p><ul>
<li>For <a class="el" href="group__aem.html#ggae99a25757035d67d1e38e288f857ff41ad2319757d74d77aad53043e893c96f83" title="SET_CONTROL command/response.">AECP_AEM_CMD_SET_CONTROL</a> commands only:<ul>
<li>make sure the CONTROL descriptor exists in the AEM model of the entity</li>
<li>On a Response with <a class="el" href="group__aem.html#gga28c8fb55a44ef0fa9474dadb507180b7a68d0c6724ca69737507f1f7b07afd4c3" title="The AVDECC Entity successfully performed the command and has valid results.">AECP_AEM_SUCCESS</a> in <a class="el" href="group__control.html#ac8402298d013b7bf0b1e09feebd6ea42" title="status field, from aecp_status_t.">genavb_aecp_msg.status</a>:<ul>
<li>If the U bit <b>is not</b> set in <a class="el" href="group__aem.html#a2453ca57616674f45f6e32646d58ab74" title="Bit field of U bit (1 for unsolicited responses, 0 in all other cases) and aecp_aem_command_type_t.">aecp_aem_pdu.u_command_type</a> (A regular <a class="el" href="group__aem.html#gga1a819286f45ec4d69fb995627756d840ac45526acdf58341f0ce63e36a7f0c09d" title="AECP message type, AEM response.">AECP_AEM_RESPONSE</a>): update the CONTROL descriptor with the value received in the command message into the descriptor and send back a response with it.</li>
<li>If the U bit <b>is set</b> in <a class="el" href="group__aem.html#a2453ca57616674f45f6e32646d58ab74" title="Bit field of U bit (1 for unsolicited responses, 0 in all other cases) and aecp_aem_command_type_t.">aecp_aem_pdu.u_command_type</a> (An unsolicited <a class="el" href="group__aem.html#gga1a819286f45ec4d69fb995627756d840ac45526acdf58341f0ce63e36a7f0c09d" title="AECP message type, AEM response.">AECP_AEM_RESPONSE</a>): validate the new value coming from the application and update the CONTROL descriptor with the new value.</li>
</ul>
</li>
<li>On a Response <b>with other than</b> <a class="el" href="group__aem.html#gga28c8fb55a44ef0fa9474dadb507180b7a68d0c6724ca69737507f1f7b07afd4c3" title="The AVDECC Entity successfully performed the command and has valid results.">AECP_AEM_SUCCESS</a> in <a class="el" href="group__control.html#ac8402298d013b7bf0b1e09feebd6ea42" title="status field, from aecp_status_t.">genavb_aecp_msg.status</a>: Send response with the current value in the descriptor</li>
</ul>
</li>
<li>If the U bit is <b>not</b> set in <a class="el" href="group__aem.html#a2453ca57616674f45f6e32646d58ab74" title="Bit field of U bit (1 for unsolicited responses, 0 in all other cases) and aecp_aem_command_type_t.">aecp_aem_pdu.u_command_type</a>, try and find a match between the response and a previously received command, based on <a class="el" href="group__aem.html#a63b4b597840f92816e511c30ef4dfb66" title="ID of the controller sending (if the message is a command), or receiving (if the message is a respons...">aecp_pdu.controller_entity_id</a> and <a class="el" href="group__aem.html#a9e38b922a840a8cd7ecad5f75ba09454" title="Sequence ID of the message, determined by the controller that sent the command (if any).">aecp_pdu.sequence_id</a>. If a previously received command is found, the response, with values from the descriptor, will be sent to the originating controller entity, and the stack will stop sending IN_PROGRESS responses for that command.Otherwise (no previously received command is found), the response is not sent and no update is performed. If the U bit is set, those checks will be skipped.</li>
<li>If the command the response is for is subject to unsolicited notifications, loop through all controllers registered for unsolicited notifications, and send an unsolicited response to them.</li>
</ul>
<hr  />
 </div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.8.5-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul class="foot">
    <li class="footer"> &copy; 2017-2020 NXP
    </li>
  </ul>
</div>
</body>
</html>
